Document

NAME

DESCRIPTION

Loading and Storing

The document's data is loaded from and stored into a file. Document creates and opens the file when necessary and then calls the method DoRead and the method DoWrite. These methods must be overridden to read and write the document's data. The Object Input/Output mechanism is normally used for reading and writing (see cookbook Object Input/Output).
It is also possible to import data from another file into the document. To use this the method CanImportDocument and the method DoImport must be overridden. The first method has to check whether the file can be imported at all and the second has to do the actual work.

Document Type

Every document has a type which is stored in the instvar docType. The type is written to the file when the document is saved. This allows to determine the document type of a file when it is reopened later. The type is passed to the method CanOpenDocument and the method CanImportDocument to check whether the file can be opened or imported.

Windows and Icon

Each document has a main window. The main window must be created by the method DoMakeWindows and is added to the document's list of windows in the instvar windows. The layout of the main window usually contains a view to present the document's data to the user. For example, a text editor would have a TextView installed in the main window. Other windows which logically belong to the document can be added to the list with the method AddWindow, e.g. the "Find/Change" dialog.
A document can be iconified and deiconified by the method Toggle. This method closes all the windows contained in the list and opens an icon window instead. The icon window is created by the method DoMakeIcon.

Commands and Change Management

The method PerformCommand executes commands. The last executed command is saved in the instvar lastCmd so that it can be undone or redone later by the method Undo. Whenever a command is performed or undone the document updates the instvar changeCount. The change count indicates whether a document is modified and therefore has unsaved changes. For example, if a document has been modified and is to be closed, then an alert is popped up which allows the user to decide what to do with the changes.

classes are always derived from Document.
class Document is never reused directly.
class Document is abstract.
class Document contains 51 methods.

owner of class:

nobody.

baseclasses:

EvtHandler

subclasses:

CmdHistDocument

flags:

EvtFlags

INSTANCE VARIABLES

application (protected Application *)

represents the application this document belongs to. Whenever the application adds a document to its list it calls the method SetApplication which sets this instance variable. application is returned as next event handler by the method GetNextHandler. It is also used to call some document handling methods of the application. The application is additionally accessible through the var gApplication.

changeCount (protected int)

contains the number of changes performed on this document since the last save operation. Documents are changed by command objects which are instances of the class Command. The method PerformCommand executes commands through the method Command::Do which returns the actual number of changes caused by the command. This number is added to the current changeCount and the new value is set with the method SetChangeCount. The same happens when a command is "undone" with the exception that the method Command::Undo returns a negative value so that the changeCount is decremented. Whenever the method Load loads a new document the changeCount is initialized to 0 by the method InitChangeCount. The changeCount should not be modified directly. It can be accessed with the method GetChangeCount.

docName (protected char *)

contains the name of the document. Unless the document is new and therefore "untitled" (see instvar isUntitled) the docName is equal to the name of the associated file. The docName is accessed by the method GetName and modified by the method SetName. The method SetName passes it to the method SetWindowTitle and the docName is also used as title for the instvar icon. If the docName contains only the file name, then the path can be accessed by the method GetLoadDir or the instvar loadDir.

docType (protected const char *)

contains the type of the document. It is initialized by the constructor. If an application handles only one type of documents, then the docType is usually equal to the main document type of the application (see class Application). Whenever a document is saved the method DoWrite saves the docType into the file so that the type can be checked later by the method CanLoadDocument or the method Application::CanOpenDocument.
Document types are defined by constants, e.g. const char *cDocTypeMyType = "MYDOCTYPE";. ET++ has a pre-defined set of document types (see class FileType). For example, a document which handles pure ASCII files would set docType to const cDocTypeAscii.

icon (protected Icon *)

is the icon window which is opened or closed when a document's windows are (de)iconified through the method Toggle. It is initially NULL and is created by the method DoMakeIcon when the document is iconified the first time (delayed creation). By default, the method DoMakeIcon creates an instance of the class Icon.

isConverted (protected bool)

indicates whether there is a difference between the instvar docType and the type of the file opened by the document. If the types are different it is assumed that the file's data must have been converted somehow during loading or will be converted before saving. After reading the data the method Load finds out this difference and sets isConverted accordingly. Actually the types can differ only if the method CanLoadDocument checks for other types than the instvar docType.
The purpose of all this is to avoid that a converted document overwrites the original file. Document ensures this by calling the method SaveAs instead of the method Save if isConverted is set. See also instvar isUntitled.

isOpen (protected bool)

tells whether the document is still open or has already been closed. It is set by the constructor. The method Close uses it to ensure that the document is closed and changes are saved only once.

isUntitled (protected bool)

indicates whether the document is new and therefore "untitled". isUntitled is TRUE if the document has just been created and has not performed a load or save yet, e.g. a document created when the user selects the "new" button of the application window. The application initializes the name of an untitled document with the string "untitled.%d" where "%d" is the current number of untitled documents within the application.
Document calls the method SaveAs instead of the method Save if isUntitled is set because the user has to enter a file name before saving. See also instvar isConverted.

lastCmd (protected Command *)

contains the last executed command. Commands are executed the first time by the method PerformCommand and undone or redone by the method Undo. Immediately after a load or a save the undo mechanism is reset. The lastCmd is then set to gResetUndo. lastCmd initially contains gNoChanges. lastCmd is directly modified by the class CmdHistDocument.
Known Problems: See method ~Document.

loadDir (protected char *)

contains the path name of the loaded file. The full name of the file can therefore be constructed by appending a "/" and the instvar docName to the loadDir. The loadDir is needed by the method Save because the document name need not contain the full path name and the current working directory can change between loading and saving.

makeBackup (protected bool)

controls the creation of backup files. The method MakeBackup, which is called before each save operation, creates a backup file if makeBackup is set. It is initially FALSE but can be modified with the method EnableBackups.

menu (protected Menu *)

is the popup menu returned by the method GetMenu. The menu is created in the constructor with the title "edit". Menu items are added later by the method DoCreateMenu immediately before the menu is shown the first time.

uniqueId (protected int)

is a number which uniquely identifies the document. This number is initialized to 0 in the constructor. Whenever a file is read or written an instance of the class FileType is created which contains information about the file. Part of the information is a number (see method FileType::UniqueId) which is copied to uniqueId and allows to identify the document within the application (see method Application::FindDocument). The uniqueId can be accessed with the method UniqueId.

wasopen (protected bool *)

wasopen is unused.

window (protected Window *)

contains the so called main window of the document because it is the first opened window and usually displays the document's data. The main window is created by the method DoMakeWindows and can be accessed through the method GetWindow. It is also stored as first entry in the instvar windows.

windows (protected ObjList *)

is the document's list of windows whereby the first entry is identical with the instvar window, the document's main window. New windows can be added with the method AddWindow. Typical windows added to this list are modeless dialogs, e.g. the "Find/Change" dialog window. Adding windows to this list is useful because they are included in (de)iconifying by the method Toggle.
windows is initialized in the constructor with an instance of the class ObjList. The destructor destroys windows and the main window, which is the first entry in the list, but not the other windows contained in the list.

INSTANCE METHOD LIST

change management

AlertChanges
GetChangeCount
InitChangeCount
Modified
SetChangeCount

commands

PerformCommand

constructor

Document

destructor

~Document

document attributes

GetDocumentType
GetLoadDir
GetName
IsUntitled
SetName
UniqueId

event handling

SetApplication

icon

DoMakeIcon
Toggle

input/output

CanImportDocument
CanLoadDocument
DoFileIsAlreadyOpen
DoImport
DoRead
DoWrite
EnableBackups
Load
MakeBackup

menu commands

Close
Import
Open
Redo
Revert
Save
SaveAs
Undo

miscellaneous

Control
DoCreateMenu
DoMenuCommand
DoSetupMenu
GetMenu
GetNextHandler
InspectorId
Parts

storing

Store

windows

AddWindow
DoMakeViews
DoMakeWindows
GetWindow
MakeFileDialog
OpenWindows
SetWindowTitle
ShowDocument

CATEGORIES

Application Framework

FILES

declaration:

Document.h

KNOWN PROBLEMS

The command gResetUndo should be executed by the method Load and the method Store themselves and not by their callers: method Open, method Close, method Save and method SaveAs. By the way, PerformCommand(gResetUndo) is missing in the method Revert.  

HISTORY

Index

NAME

DESCRIPTION

INSTANCE VARIABLES

INSTANCE METHOD LIST

CATEGORIES

FILES

KNOWN PROBLEMS

HISTORY